\subsection{Castability Functions \texttt{<}upc\_castable.h\texttt{>}}
\label{upc-castable}
\index{privatizability}
\index{castability}
\index{upc\_castable.h}
\index{\_\_UPC\_CASTABLE\_\_}

\npf A UPC implementation may map some or all of the shared address space
of another thread into the local address space of the current thread.  The
functions described in this section allow the programmer to determine
whether this is the case, and to make use of this information by
providing the ability to obtain valid local addresses for shared cells
with affinity to other threads.  This capability, sometimes called
"privatizability", is referred to as "castability" in this section.

\np Implementations that support this interface shall predefine the
feature macro {\_\_UPC\_CASTABLE\_\_} to the value 1.

\subsubsection{Standard headers}

\npf The standard header is

{\tt <upc\_castable.h>}

\subsubsection{Castability Functions}

\paragraph{The {\tt upc\_cast} function}
\index{upc\_cast}
\index{cast}

{\bf Synopsis}

\npf\vspace{-2.5em}
\begin{verbatim}
    #include <upc_castable.h>
    void *upc_cast(shared void *ptr);
\end{verbatim}

{\bf Description}

\np The {\tt upc\_cast} function converts the specified
pointer-to-shared to a valid pointer-to-local.  If such a conversion
is not possible, the value NULL is returned.  The conversion will be considered possible only if the returned
pointer-to-local may be used to read and write the target thread's
entire contiguous portion of the largest shared object
containing the specified shared address.

\np If the conversion is possible, the pointer is referred to as {\em castable}.
\index{castable}

\np If the target of the {\tt ptr} pointer has affinity to the current
thread, {\tt upc\_cast(ptr)} is equivalent to {\tt (void *)ptr}.

\np If the {\tt ptr} pointer is null, {\tt upc\_cast} returns NULL.

\np The pointer returned by {\tt upc\_cast} is valid only in the calling
thread.  It cannot be assumed that the return value may be passed to
a different thread and used by that thread.  It also cannot be assumed that two
threads calling {\tt upc\_cast} with the same argument will get the same
return value.

\paragraph{The {\tt upc\_thread\_info} function}
\index{upc\_thread\_info}

{\bf Synopsis}

\npf\vspace{-2.5em}
\begin{verbatim}
    #include <upc_castable.h>
    upc_thread_info_t upc_thread_info(int threadId);
\end{verbatim}

{\bf Description}

\index{upc\_thread\_info\_t}
\np The {\tt upc\_thread\_info} function returns information about
potential uses of the {\tt upc\_cast} function on objects with
affinity to the specified thread.  The information is returned in a
{\tt upc\_thread\_info\_t} structure, with the following fields:

\begin{description}
\item{\tt int guaranteedCastable}
Indicates which memory regions are guaranteed to be castable.
\item{\tt int probablyCastable}
Indicates which memory regions are likely (but not guaranteed)
to be castable.
\end{description}

\np An implementation may provide additional fields in this structure,
allowing {\tt upc\_thread\_info} to return other information about
the specified thread.

\np The {\tt guaranteedCastable} and {\tt probablyCastable} fields
contain coded integer values indicating memory regions.  If the flag
for a particular region is set in the {\tt guaranteedCastable} field,
it indicates that
any pointer into that region in the specified target thread's memory is
castable.  If the flag is
set for a particular region is set in the {\tt probablyCastable} field,
it indicates that it is likely, but not guaranteed, that a pointer into
that region is castable.

\np Flag values are as specified below.  Multiple flag values may be
combined using the bitwise OR operator ({\textbar}).  Each flag has a
unique bitwise representation that can be unambiguously tested using the
bitwise AND operator (\&).

\begin{description}
\item[{\tt UPC\_CASTABLE\_NONE}] \hfill \\
No memory regions are indicated by this field.  {\tt UPC\_CASTABLE\_NONE}
shall be defined to be zero.
\item[{\tt UPC\_CASTABLE\_ALL\_ALLOC}] \hfill \\
Refers to memory allocated via {\tt upc\_all\_alloc}.
\item[{\tt UPC\_CASTABLE\_GLOBAL\_ALLOC}] \hfill \\
Refers to memory allocated via {\tt upc\_global\_alloc}.
\item[{\tt UPC\_CASTABLE\_ALLOC}] \hfill \\
Refers to memory allocated via {\tt upc\_alloc}.
\item[{\tt UPC\_CASTABLE\_STATIC}] \hfill \\
Refers to shared variables defined via static and file scope declarations.
\item[{\tt UPC\_CASTABLE\_ALL}] \hfill \\
Refers to all regions of shared memory.  {\tt UPC\_CASTABLE\_ALL} shall
be defined to be all the region-specific values combined via bitwise
OR ({\textbar}) operations.
\end{description}

\pagebreak
\appendix
